Magnum One/Magnum One (Mid-American Digital) (Disc Manufacturing).iso/d8/warpcomm.arc/WARPCOMM.DOC

Text File | 1991-01-25 | 13KB | 472 lines

                    The Warp Communications Library

                              Version 1.02

                                written

                                   by

                              Trevor Bell

                             Copyright 1991


WHAT IT IS:

        The Warp Communications Library is a full-featured modem/serial
communications library.  It can be used to create BBS doors, protocols,
terminal programs, or actual BBS programs.  Currently the library only
supports Turbo C and Turbo C++ with libraries for each however support
for MSC is on the way and if you are a registered user with the source
code then you could easily modify the source to work with any C
compiler.

        Warp Comm is NOT PUBLIC DOMAIN, Warp Comm IS SHAREWARE.  A
registration fee of $25 (of course I won't mind if you send more than
$25) is required if you wish to use Warp Comm in any application to be
distributed to the general public.  Registration will get you the full
source code for both the Turbo C and Turbo C++ libraries and library files
for each of the 6 memory models (tiny, small, medium, compact, large, huge).
Without registration you will be limited to compiling programs in the small
memory model and this will substantially limit programs.  By registering
this program you will be contributing to the release of future versions
of Warp Comm and future programs that I will be creating.  Your
registration will be greatly appreciated.  See the file ORDER.FRM for
details on registering.

Registrations may be sent to:

        Trevor Bell
        P.O. Box 4173
        Redondo Beach, CA  90278
        Galleria Station

I can be contacted on THE SOURCE BBS at 213-371-3737.


Two zip files are provided, one for Turbo C and Turbo C++ in standard
C mode and one for Turbo C++ only in C++ mode.  They are:

TC.ZIP  (For C only)
TCP.ZIP (For C++ only)



HOW TO USE IT:

--------------------------------------------------------------------------------

               For Turbo C++ and Turbo C users in C mode

--------------------------------------------------------------------------------

The file WARPCOMM.H must be included in any program wishing to use the
Warp Comm library in TC, and the library file WCOMMS.LIB must be linked with
the program.


Opening the Com Port:
---------------------

open (baud_rate, interrupt_request, base_address,
        receive_buffer_size, transmit_buffer_size);

baud_rate - the baud rate to open the com port at

interrupt request - which IRQ to open the comport at, usual values are
        as follows:

        COM port 1: IRQ 4
        COM port 2: IRQ 3

        all other COM ports are non-standard and would be machine
        dependent.

base_address - which base address to use, common values are as follow:

        COM port 1: 0x3f8 (Hex)
        COM port 2: 0x2f8 (Hex)

receive buffer size - this can vary with modem speed and the application
        being used however, 2000 characters is usually a good place to start.

transmit buffer size - this can vary with modem speed and the application
        being used however, 2000 characters is usually a good place to start.

Thus opening COM 1 at 2400 baud would work like this:

        com_open(2400, 4, 0x3F8, 2000, 2000);


Outputting to the Com Port:
---------------------------

Outputting to the comport in TC is accomplished like this:

char value = 13;
com_out_char(value);


Inputting from the Com Port:
----------------------------

Inputting from the comport in TC is accomplished like this:

char value;
value=com_get_char();


Checking for a character waiting to be read:
--------------------------------------------

Often it is necessary to know if there is a character waiting in the com
port receive buffer, this can be checked with the char_waiting function
which returns a 1 if there is a character or characters waiting, and a 0
if the com port buffer is empty.  It is used like this:

char value;

if( char_waiting()) {
    value=com_get_char();
}


Closing the Com Port:
---------------------

Closing out the com port is a simple task, it will disable com port
interrupt routine, and free the memory allocated by the transmit and receive
buffers.  It is used like this:

com_close();


Sending a string to the Com Port:
---------------------------------

A null terminated string can be sent to the com port like this:

char *string="This is a null-terminated string.";
com_out_char_str(string);

an alternate method of sending strings to the modem can also be used,
like this:

send_modem_string("ATZ|");

where the | command represents a carriage return.



Sending a buffer to the Com Port:
---------------------------------

A buffer of a specified size can be sent to the com port like this:

unsigned char *buffer;
unsigned int length=10;
com_out_buf(buffer,length);


Receiving a buffer from the Com Port:
-------------------------------------

A buffer of a specified size can be received from the com port like this:

unsigned char *buffer;
unsigned int length=10;
com_get_buf(buffer,length);


Setting the DTR pin of the modem:
---------------------------------

The DTR pin of the modem can be changed like this:

set_dtr(1);

A value of 1 will hold the DTR high, a value of 0 will hold it low
causing most modems to hangup.


Setting the RTS pin of the modem:
---------------------------------

The RTS pin of the modem can be changed like this:

set_rts(1);

A value of 1 will hold the RTS high allowing some modems to use hardware
flow control (consult your modem manual on this), a value of 0 will
hold it low.


Clearing the transmit or receive buffers:
-----------------------------------------

Clearing the transmit buffer will clear any characters waiting to be
sent to the com port and is accomplished like this:

clear_xmit_buffer();

Clearing the receive buffer will clear any characters waiting to be
received the com port and is accomplished like this:

clear_receive_buffer();


Changing the baud rate:
-----------------------

Changing the baud rate on the modem is accomplished like this:

set_baudrate(2400);


Detecting a Carrier:
--------------------

The carrier detect pin of the modem can be checked by examining the
integer variable CD.  If CD is 1 then a carrier is present, if CD is 0
then no carrier is present.  It can be used like this:

if(CD==1) {
    puts("A carrier is detected.");
}

--------------------------------------------------------------------------------

                      Turbo C++ users in C++ mode

--------------------------------------------------------------------------------

The file WARPCOMM.HPP must be included in any program wishing to use the
Warp Comm library in TC++, and the library file WCOMMS.LIB must be linked with
the program.  In the Turbo C++ versions of the library all the commands
and most of the data structures are contained within the COM_port class,
and thus must be accessed through the variable remote which is defined
like this:

COM_port remote;

Opening the Com Port:
---------------------

remote.open (baud_rate, interrupt_request, base_address,
        receive_buffer_size, transmit_buffer_size);

baud_rate - the baud rate to open the com port at

interrupt request - which IRQ to open the comport at, usual values are
        as follows:

        COM port 1: IRQ 4
        COM port 2: IRQ 3

        all other COM ports are non-standard and would be machine
        dependent.

base_address - which base address to use, common values are as follow:

        COM port 1: 0x3f8 (Hex)
        COM port 2: 0x2f8 (Hex)

receive buffer size - this can vary with modem speed and the application
        being used however, 2000 characters is usually a good place to start.

transmit buffer size - this can vary with modem speed and the application
        being used however, 2000 characters is usually a good place to start.

Thus opening COM 1 at 2400 baud would work like this:

        remote.open(2400, 4, 0x3F8, 2000, 2000);


Outputting to the Com Port:
---------------------------

Outputting to the comport in TC++ is identical to file stream output,
you simply use the overloaded bitshift operator with the variable to
output to the port, like this:

char value = 13;
remote << value;


Inputting from the Com Port:
----------------------------

Inputting from the comport in TC++ is identical to file stream input,
you simply use the overloaded bitshift operator with the variable to
input from the port, like this:

char value;
remote >> value;


Checking for a character waiting to be read:
--------------------------------------------

Often it is necessary to know if there is a character waiting in the com
port receive buffer, this can be checked with the char_waiting function
which returns a 1 if there is a character or characters waiting, and a 0
if the com port buffer is empty.  It is used like this:

char value;

if( remote.char_waiting()) {
    remote >> value;
}


Closing the Com Port:
---------------------

Closing out the com port is a simple task, it will disable com port
interrupt routine, and free the memory allocated by the transmit and receive
buffers.  It is used like this:

remote.close();


Sending a string to the Com Port:
---------------------------------

A null terminated string can be sent to the com port like this:

char *string="This is a null-terminated string.";
remote << string;

an alternate method of sending strings to the modem can also be used,
like this:

remote.send_modem_string("ATZ|");

where the | command represents a carriage return.


Sending a buffer to the Com Port:
---------------------------------

A buffer of a specified size can be sent to the com port like this:

unsigned char *buffer;
unsigned int length=10;
remote.out_buf(buffer,length);


Receiving a buffer from the Com Port:
-------------------------------------

A buffer of a specified size can be received from the com port like this:

unsigned char *buffer;
unsigned int length=10;
remote.get_buf(buffer,length);


Setting the DTR pin of the modem:
---------------------------------

The DTR pin of the modem can be changed like this:

remote.set_dtr(1);

A value of 1 will hold the DTR high, a value of 0 will hold it low
causing most modems to hangup.


Setting the RTS pin of the modem:
---------------------------------

The RTS pin of the modem can be changed like this:

remote.set_rts(1);

A value of 1 will hold the RTS high allowing some modems to use hardware
flow control (consult your modem manual on this), a value of 0 will
hold it low.


Clearing the transmit or receive buffers:
-----------------------------------------

Clearing the transmit buffer will clear any characters waiting to be
sent to the com port and is accomplished like this:

remote.clear_xmit_buffer();

Clearing the receive buffer will clear any characters waiting to be
received the com port and is accomplished like this:

remote.clear_receive_buffer();


Changing the baud rate:
-----------------------

Changing the baud rate on the modem is accomplished like this:

remote.set_baudrate(2400);


Detecting a Carrier:
--------------------

The carrier detect pin of the modem can be checked by examining the
integer variable CD.  If CD is 1 then a carrier is present, if CD is 0
then no carrier is present.  It can be used like this:

if(remote.CD==1) {
    puts("A carrier is detected.");
}


--------------------------------------------------------------------------------

                             CODE EXAMPLES

--------------------------------------------------------------------------------


A very simple terminal program is provided with Warp Comm to demonstrate
it's capabilities very minimally.  Feel free to modify it to your
heart's desire, keep in mind however that without registration your
program will need to remain within the small memory model.

The source code for this program is provided in the file TERM.C or
TERM.CPP for TC and TC++.



--------------------------------------------------------------------------------

                                SUPPORT

--------------------------------------------------------------------------------


Support can be obtained through mail sent to my PO Box or by calling the
following BBS:

        The Source
        213-371-3737


--------------------------------------------------------------------------------

                            VERSION HISTORY

--------------------------------------------------------------------------------


Version 1.00:
        not released to the public

Version 1.01:
        My first release!

Version 1.02:
        Fixed null pointer assignment.